Skip to content

docs: fix all findings from the documentation audit#49

Merged
andybons merged 2 commits into
mainfrom
docs-fixes
Jul 15, 2026
Merged

docs: fix all findings from the documentation audit#49
andybons merged 2 commits into
mainfrom
docs-fixes

Conversation

@andybons

@andybons andybons commented Jul 15, 2026

Copy link
Copy Markdown
Contributor

What

Fixes every confirmed finding from a full adversarially-verified documentation audit of this repo (5 audit agents → 2 sweep lenses → 37 independent verifiers → synthesis, with human re-verification of disputed refutations).

Two commits:

  1. fix(examples): gen-ca.sh rewritten to generate from an explicit OpenSSL config instead of -addext, and EC keygen split into ecparam + req. The old script produced CAs Go rejects on Homebrew OpenSSL 1.1.1 (duplicate extension with OID "2.5.29.19") and macOS LibreSSL 3.3.6 (invalid ECDSA parameters). Both failures were reproduced live before the fix and the new script verified through proxy.LoadCA on both toolchains.

  2. docs: every doc correction —

    • Reproduced breakages: quick-start now works as literally written (verified end-to-end with a real intercepted request); the install verify step no longer claims --config /dev/null errors (it starts and blocks — replaced with the no-config exit-1 path).
    • Factually wrong claims fixed: LLM policy denial is 400 not 200; KeepEngines is scope-keyed (llm-gateway/http/mcp-<server>) with a hardcoded api.anthropic.com gate, not hostname-keyed; grant documents the claude tie-break; token-exchange cache TTL is a 1-minute hard cap, not a 5-minute default; credential host matching strips any port and rejects : in config (the 80/443 semantics belong to network policy); MCP SSE uses a per-chunk-flushing loop, not io.Copy; injected_headers values are lowercased.
    • Newly documented: HTTP-scope Keep policy (403 + X-Moat-Blocked: keep-policy), 401/403 credential invalidation + 10s cooldown, OTEL_SDK_DISABLED, the daemon-mode /mcp/{token}/{server} path, ALPN negotiation, five missing canonical-log fields, postgres in proxy_type.
    • Top-level: README gains MCP relay / LLM policy / host gateway sections, a docs link, and the ghcr.io install path; AGENTS.md architecture tree completed and OTel section updated; docs/token-exchange-endpoint.md de-orphaned and reconciled (singleflight); changelog PR links restored (fix(proxy): match wildcard host patterns in credential lookup #43–fix(otel): stop OTel export failures from flooding INFO logs #47) and a v0.17.1 entry added.

Every changed claim was re-verified against code by the fixing agent and independently re-checked in review (including running the new gen-ca.sh on both OpenSSL builds and confirming the claude tie-break direction against selectWinners).

Verification

  • go build ./... clean (docs + one shell script; no Go changes)
  • shellcheck examples/gen-ca.sh clean
  • Quick-start executed end-to-end as written post-fix
  • All new internal doc links resolve

andybons added 2 commits July 14, 2026 23:58
@andybons
fix(examples): make gen-ca.sh portable across OpenSSL builds
86009ad 
The script's -addext basicConstraints combined with some OpenSSL builds'
default req_extensions to emit the extension twice, producing a CA that
Go rejects with 'duplicate extension with OID 2.5.29.19' (Homebrew
OpenSSL 1.1.1). LibreSSL's one-step EC keygen emitted parameters Go
rejects with 'invalid ECDSA parameters'. Generate from an explicit
OpenSSL config and split keygen into ecparam + req, verified on both
toolchains through proxy.LoadCA.
@andybons
docs: correct audit findings across guides, concepts, reference, and …
c324782 
…top-level docs

Fixes every confirmed finding from an adversarially-verified docs audit:
the two live-reproduced getting-started failures (quick-start cd/path
mismatch, --config /dev/null verify step), five reference/concept
corrections (LLM denial 400 not 200, KeepEngines scope keying, grant
claude tie-break, token-exchange 1-minute hard cap, credential host
matching semantics, MCP SSE flush mechanism), and newly documents the
HTTP-scope Keep policy layer, 401/403 credential invalidation,
OTEL_SDK_DISABLED, the daemon-mode MCP path, ALPN negotiation, and the
missing canonical log fields. Adds README sections for MCP relay, LLM
policy, and host gateway plus the container image install path, updates
the AGENTS.md architecture tree, de-orphans docs/token-exchange-endpoint.md,
and restores the changelog PR-link convention.
@claude

claude Bot commented Jul 15, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Claude finished @andybons's task in 2m 33s —— View job

Reviewing PR #49

  • Gather context (PR diff, changed files)
  • Review examples/gen-ca.sh and doc changes against source
  • Verify high-risk factual claims against code
  • Post summary

Summary

This PR is docs-only plus a rewrite of examples/gen-ca.sh. I fact-checked the highest-risk claims (the ones the PR body flags as "factually wrong claims fixed" or "newly documented") directly against the source, since that's exactly the bug class this PR targets:

  • LLM policy denial status — confirmed http.StatusBadRequest (400), not 200 (proxy/proxy.go:2496,2507,2519).
  • KeepEngines scope keys — confirmed "llm-gateway", "http", "mcp-<server>", with a hardcoded host == "api.anthropic.com" gate (proxy/proxy.go:2747-2749, proxy/mcp.go:274).
  • grant: claude tie-break — confirmed opposite-direction tie-break logic exists exactly as documented (proxy/proxy.go:1320-1334,1363-1364).
  • Token-exchange cache TTL — confirmed maxTokenTTL = time.Minute hard cap, not a 5-minute default (credentialsource/tokenexchange.go:153).
  • Credential invalidation cooldown — confirmed defaultInvalidateCooldown = 10 * time.Second (credentialsource/tokenexchange.go:164).
  • Credential host matching — confirmed isValidHost rejects : (proxy/proxy.go:1006-1019) and lookupHostKeyed/bareHost strip the port unconditionally with no 80/443 default.
  • MCP SSE streaming — confirmed a 4096-byte per-chunk flush loop (streamResponseBody, proxy/stream.go), used by mcp.go:484, not io.Copy.
  • injected_headers lowercased — confirmed InjectedHeaders keys are produced via strings.ToLower(headerName) throughout.
  • HTTP-scope Keep policy — confirmed 403 + X-Moat-Blocked: keep-policy (proxy/proxy.go:2930-2932), distinct from network policy's 407/request-rule.
  • OTEL_SDK_DISABLED — confirmed strings.EqualFold(getenv("OTEL_SDK_DISABLED"), "true") (cmd/gatekeeper/main.go:36).
  • Daemon-mode /mcp/{token}/{server} path — confirmed in handleDirectMCPRelay (proxy/proxy.go:1777-1797).
  • ALPN negotiation / http2.Transport — confirmed NextProtos: []string{http2.NextProtoTLS, "http/1.1"} and the h2/http.Transport split (proxy/proxy.go:2590,2626).
  • Canonical log fields — confirmed RequestSize, ResponseSize, RequestMessages, ResponseMessages fields exist with the documented semantics (proxy/proxy.go:178-181).

All matched the docs. I didn't find any remaining doc/code mismatches in the sampled claims.

examples/gen-ca.sh — the rewrite (heredoc'd OpenSSL config + split ecparam/req steps) is a straightforward, correct fix for the two described toolchain failures. No shell scripting bugs (proper set -euo pipefail, quoted variables, trap cleanup for the temp config file). One minor, pre-existing (not introduced by this diff) note: ca.key is written by openssl ecparam before the chmod 0600 on the next line, so there's a brief window where the key file has default umask permissions — same as the original script's behavior via -keyout, not a regression, and low-severity for a local example/dev script.

No inline comments filed — nothing rose to the level of a code defect.

@andybons andybons merged commit 1b66c2a into main Jul 15, 2026
2 checks passed
@andybons andybons deleted the docs-fixes branch July 15, 2026 12:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@andybons